From: Ian Jackson Date: Fri, 11 May 2012 17:59:06 +0000 (+0100) Subject: libxl: clarify definition of "slow" operation X-Git-Tag: archive/raspbian/4.8.0-1+rpi1~1^2~8478 X-Git-Url: https://dgit.raspbian.org/%22http:/www.example.com/cgi/%22https://%22%22/%22http:/www.example.com/cgi/%22https:/%22%22?a=commitdiff_plain;h=99e96537fdac1d2ca36d6ce60532eebd3ae52657;p=xen.git libxl: clarify definition of "slow" operation Update the comment in libxl_internal.h to be clearer about which application-facing libxl operations need to take an ao_how. Reported-by: Dan Magenheimer Signed-off-by: Ian Jackson Acked-by: Ian Campbell Committed-by: Ian Jackson --- diff --git a/tools/libxl/libxl_internal.h b/tools/libxl/libxl_internal.h index 3aa0ed7f30..9f3f759fea 100644 --- a/tools/libxl/libxl_internal.h +++ b/tools/libxl/libxl_internal.h @@ -1439,17 +1439,34 @@ _hidden void libxl__egc_cleanup(libxl__egc *egc); /* * Machinery for asynchronous operations ("ao") * - * All "slow" functions (includes anything that might block on a - * guest or an external script) need to use the asynchronous - * operation ("ao") machinery. The function should take a parameter - * const libxl_asyncop_how *ao_how and must start with a call to - * AO_INITIATOR_ENTRY. These functions MAY NOT be called from - * inside libxl, because they can cause reentrancy callbacks. + * All "slow" functions (see below for the exact definition) need to + * use the asynchronous operation ("ao") machinery. The function + * should take a parameter const libxl_asyncop_how *ao_how and must + * start with a call to AO_INITIATOR_ENTRY. These functions MAY NOT + * be called from inside libxl, because they can cause reentrancy + * callbacks. * * For the same reason functions taking an ao_how may make themselves * an egc with EGC_INIT (and they will generally want to, to be able * to immediately complete an ao during its setup). * + * + * "Slow" functions includes any that might block on a guest or an + * external script. More broadly, it includes any operations which + * are sufficiently slow that an application might reasonably want to + * initiate them, and then carry on doing something else, while the + * operation completes. That is, a "fast" function must be fast + * enough that we do not mind blocking all other management operations + * on the same host while it completes. + * + * There are certain primitive functions which make a libxl operation + * necessarily "slow" for API reasons. These are: + * - awaiting xenstore watches (although read-modify-write xenstore + * transactions are OK for fast functions) + * - spawning subprocesses + * - anything with a timeout + * + * * Lifecycle of an ao: * * - Created by libxl__ao_create (or the AO_CREATE convenience macro).